CU Amiga Super CD-ROM 14

home *** CD-ROM | disk | FTP | other *** search

/ CU Amiga Super CD-ROM 14 / CU Amiga Magazine's Super CD-ROM 14 (1997)(EMAP Images)(GB)(Track 1 of 3)[!][issue 1997-09].iso / CUCD / Programming / XPK / Developer / Autodocs / xpkmaster.doc next >

Wrap

Text File | 1997-06-17 | 27.8 KB | 779 lines

TABLE OF CONTENTS xpkmaster.library/XpkAllocObject xpkmaster.library/XpkClose xpkmaster.library/XpkExamine xpkmaster.library/XpkFault xpkmaster.library/XpkFreeObject xpkmaster.library/XpkOpen xpkmaster.library/XpkPack xpkmaster.library/XpkPassRequest xpkmaster.library/XpkPrintFault xpkmaster.library/XpkQuery xpkmaster.library/XpkRead xpkmaster.library/XpkUnpack xpkmaster.library/XpkWrite xpkmaster.library/--tags-- xpkmaster.library/--progress-- xpkmaster.library/--data hooks-- xpkmaster.library/XpkAllocObject xpkmaster.library/XpkAllocObject NAME XpkAllocObject - Allocate memory for xpk related structures (V4) SYNOPSIS ptr = XpkAllocObject(type, tags) D0 D0 A0 APTR XpkAllocObject(ULONG , struct TagItem *) ptr = XpkAllocObjectTags(type, firsttag, ...) APTR XpkAllocObjectTags(ULONG, Tag, ...) FUNCTION This function allocates the memory of a needed xpk related structure and initializes it. It should help to bring better upwards compatibility in next versions. Use it always in newer code. INPUT type - in xpk/xpk.h defined XPKOBJ_... types. for example XPKOBJ_FIB alloctes XpkFib structure tags - Pointer to an array of struct TagItem. No tags defined at the moment. RESULT ptr - Pointer to allocated memory of needed size or 0 when an error occured. SEE ALSO xpk/xpk.h, XpkFreeObject() xpkmaster.library/XpkClose xpkmaster.library/XpkClose NAME XpkClose - Close an XPK-File SYNOPSIS err = XpkClose(xfh) D0 A0 LONG XpkClose(struct XpkFib *) FUNCTION Frees all resources associated with packing or unpacking an XPK-File. Note that this may well fail, especially on packing, since additional writes have to be made here. INPUT xfh - The Struct XpkFib obtained from XpkOpen() RESULT err - Global Xpk error code SEE ALSO XpkOpen(), XpkRead(), XpkWrite() xpkmaster.library/XpkExamine xpkmaster.library/XpkExamine NAME XpkExamine - Get information about a compressed file SYNOPSIS err = XpkExamine(fib, tags) D0 A0 A1 LONG XpkExamine(struct XpkFib *, struct TagItem *) err = XpkExamineTags(fib, firsttag, ...) LONG XpkExamineTags(ULONG, Tag, ...) FUNCTION Returns information about compressed data. The output is written to the XpkFib structure whose address is passed with the mandatory XPK_FileExamine tag. You also have to specify an XPK_In* tag. Note that the file position of the in hook will not be altered. XPK_GetError is supported. A tag field has to end with TAG_DONE. INPUT tags - Pointer to an array of struct TagItem. You may use either a XPK_InBuf, a XPK_InName, XPK_InFH or XPK_InHook tag. RESULT err - Global Xpk error code SEE ALSO xpk/xpk.h xpkmaster.library/XpkFault xpkmaster.library/XpkFault NAME XpkFault - Returns the text associated with a Xpk error code (V4) SYNOPSIS len = XpkFault(code, header, buffer, len) D0 D0 A0 A1 D1 LONG XpkFault(LONG, STRPTR, STRPTR, LONG) FUNCTION This routine obtains the error message text for the given error code. The header is prepended to the text of the error message, followed by a colon. Puts a null-terminated string for the error message into the buffer. At most len bytes are written to buffer. INPUTS code - Error code (negative value or 0) header - header to output before error text buffer - Buffer to receive error message. len - Length of the buffer. RESULT len - number of characters put into buffer (may be 0) SEE ALSO XpkPrintFault() xpkmaster.library/XpkFreeObject xpkmaster.library/XpkFreeObject NAME XpkFreeObject - Frees memory allocated with XpkAllocObject() (V4) SYNOPSIS XpkFreeObject(type, object) D0 A0 void XpkFreeObject(ULONG , APTR) FUNCTION Frees object allocated by XpkAllocObject(). Do not call for objects allocated in any other way. INPUTS type - type passed to XpkAllocObject() object - pointer returned by XpkAllocObject() SEE ALSO xpk/xpk.h, XpkAllocObject() xpkmaster.library/XpkOpen xpkmaster.library/XpkOpen NAME XpkOpen - Open a compressed file for partial reading SYNOPSIS err = XpkOpen(xfh,tags) D0 A0 A1 LONG XpkOpen(struct XpkFib **xfh, struct TagItem *) FUNCTION Using XpkOpen you can read or write an XPK file without ever having all of the file present in RAM. On reading, you cannot pick the size of the chunks. They are given by the file to be decompressed and may be up to the whole size of the file. XPK_GetError is supported. INPUT xfh - Address of a pointer to struct XpkFib tags - Specifying XPK_PackMethod will chose packing mode for this filehandle. Only In-tags are permitted in case of unpacking, and only Out-tags are in case of packing. Anything else will yield undefined results. Progress reports not supported. When packing, you must supply XPK_InLen as well. RESULT xfh - The filehandle. Consists of an XpkFib and some private information. The NLen field in the XpkFib indicates the length of the next chunk. err - Global Xpk error code. If nonzero, no XpkFib was allocated. SEE ALSO XpkRead(), XpkWrite(), XpkClose(), xpkmaster.library/--tags-- xpkmaster.library/XpkPack xpkmaster.library/XpkPack NAME XpkPack - Compress a data stream SYNOPSIS err = XpkPack(tags) D0 A0 LONG XpkPack(struct TagItem *) err = XpkPackTags(firsttag, ...) LONG XpkPackTags(ULONG, Tag, ...) FUNCTION Compresses a file or a memory area to a different file or memory area. You need to specify at least one XPK_In... tag, at least one XPK_Out... tag, plus XPK_PackMethod. XPK_GetError is supported. A tag field has to end with TAG_DONE. INPUT tags - Pointer to an array of struct TagItem. See xpkmaster/--tags-- RESULT err - Global Xpk error code. SEE ALSO xpkmaster.library/--tags--, xpk/xpk.c xpkmaster.library/XpkPassRequest xpkmaster.library/XpkPassRequest NAME XpkPassRequest - opens a password Requester (V4) SYNOPSIS err = XpkPassRequest(tags) D0 A0 LONG XpkPassRequest(struct TagItem *) err = XpkPassRequestTags(firsttag, ...) LONG XpkPassRequestTags(ULONG, Tag, ...) FUNCTION Opens a requester to ask the user for a password. The requester can ask for a password or a 16/32 bit key. It has a tunable timeout to allow batch work. INPUT tags - Pointer to an array of struct TagItem. Either XPK_Preferences or one of the following: TAGS XPK_PassChars (ULONG) Tell the requester which characters are allowed in the password. Use XPKPASSFLG_... and XPKPASSFF_... defines. XPK_PasswordBuf (STRPTR) Pointer to memory area, where the password should be stored. Requires XPK_PassBuffSize tag. XPK_PassBufSize (ULONG) Size of the buffer passed with XPK_PasswordBuf. XPK_Key16BitPtr (UWORD *) Ask for an 16 bit key instead of a password. Data is a pointer to a 16 bit (UWORD) variable. XPK_Key32BitPtr (ULONG *) Ask for an 32 bit key. Data points to a 32 bit (ULONG) variable. XPK_PubScreen (struct Screen *) Pointer of type struct Screen of the public screen, the requester should open on. If not given, the requester opens on default public screen. XPK_PassTitle (STRPTR) Is the text, which is shown in the title line of the screen. If not given, the internal defaults are used. XPK_TimeOut (ULONG) Time after which the requester should close automatically, when no user action happend. 0 means no timeout. RESULT err - Global Xpk error code. SEE ALSO xpk/xpk.c xpkmaster.library/XpkPrintFault xpkmaster.library/XpkPrintFault NAME XpkPrintFault - Prints the text associated with a Xpk error code (V4) SYNOPSIS success = XpkPrintFault(code, header) D0 D0 A0 BOOL XpkPrintFault(LONG, STRPTR) FUNCTION This routine obtains and prints the error message text for the given error code. This is similar to the XpkFault() function, except that the output is written to the default output channel with buffered output. INPUTS code - Error code (negative value or 0) header - header to output before error text RESULT success - Success/failure code. Return of 0 means failure. SEE ALSO XpkFault() xpkmaster.library/XpkQuery xpkmaster.library/XpkQuery NAME XpkQuery - Gain information about packers SYNOPSIS err = XpkQuery(tags) D0 A0 LONG XpkQuery(struct TagItem *) err = XpkQueryTags(firsttag, ...) LONG XpkQueryTags(ULONG, Tag, ... ) FUNCTION Finds out a list of available packers or various parameters of a packer. When using the tag XPK_PackersQuery, you must supply a XpkPackerList structure and will receive a list of available packers. The second possibility, XPK_PackerQuery, expects a pointer to a XpkPackerInfo structure which will be filled in with information about a packer, and XPK_ModeQuery fills in a XpkMode structure with information about some mode (or the default mode) of a packer. XPK_PackMethod must be present among the tags for the latter two, and XPK_PackMode can be for ModeQuery. XPK_GetError is supported. Pass {XPK_Preferences, FALSE} as tags to disable the dummy packer USER, which implements the preferences packing.Then handle the preferences mode internally, as the statistics passed with XPK_ModeQuery and XPK_PackerQuery are not very useful. RESULT err - Global Xpk error code. SEE ALSO xpk/xpk.h xpkmaster.library/XpkRead xpkmaster.library/XpkRead NAME XpkRead - Unpack one part of an XPK-File SYNOPSIS read = XpkRead( xfh, buf, len ) D0 A0 A1 D0 LONG XpkRead(struct XpkFib *, UBYTE *, LONG) FUNCTION Reads one chunk from an XPK-file and decompresses it to the memory area indicated. INPUT xfh - The XpkFib obtained from XpkOpen(). It must be a read- handle, ie. there was no XPK_PackMethod tag among the tags passed to XpkOpen(). buf - The memory area to write the destination to len - The number uncompressed bytes to output. Note that you cannot choose these freely but must take them from the NLen field in the XpkFib. RESULT read - The number of bytes read. 0 indicates EOF, negative numbers are global error codes. Long error messages written to buffer passed through XPK_GetError in XpkOpen(). This number of bytes read will usually be smaller than the number requested! SEE ALSO XpkOpen(), XpkWrite(), XpkClose(), examples/ xpkmaster.library/XpkUnpack xpkmaster.library/XpkUnpack NAME XpkUnpack - Decompress a data stream SYNOPSIS err = XpkUnpack(tags) D0 A0 LONG XpkUnpack(struct TagItem *) err = XpkUnpackTags(firsttag, ...) LONG XpkUnpackTags(ULONG, Tag, ...) FUNCTION Decompresses a file or a memory area to a different file or memory area. You need to specify at least one XPK_In... tag, at least one XPK_Out... tag. A tag field has to end with TAG_DONE. XPK_GetError is supported. INPUT tags - Pointer to an array of struct TagItem. See xpkmaster/tags RESULT err - Global Xpk error code. SEE ALSO xpkmaster.library/--tags-- xpkmaster.library/XpkWrite xpkmaster.library/XpkWrite NAME XpkWrite - Pack one part of an XPK-File SYNOPSIS read = XpkWrite(xfh, buf, len) D0 A0 A1 D0 LONG XpkWrite(struct XpkFib *, UBYTE *, LONG) FUNCTION Compresses the memory area indicated and writes it to an XPK-File. INPUT xfh - The XpkFib obtained from XpkOpen(). Must be a write- handle, ie. XPK_PackMethod must have been among the tags passed to XpkOpen(). buf - The memory area to compress len - The number bytes to compress. Note you may not choose them freely, you must always deliver as many bytes as the NLen field of the XpkFib indicates. You may try to influence it by passing XPK_ChunkLen to XpkOpen(). Important: The first chunk written *must* be the biggest! RESULT written - The number of bytes written. 0 indicates EOF, negative numbers are global error codes. Error messages are written to buffer passed through XPK_GetError in XpkOpen(). SEE ALSO XpkOpen(), XpkRead(), XpkClose(), examples/ xpkmaster.library/--tags-- xpkmaster.library/--tags-- THE TAGS FOR XpkPack() AND XpkUnpack() THE INPUT TAGS. One of the four must be present. XPK_InName (STRPTR) Name of file to (de)compress. On packing, XPK_InLen can be specified in order to pack only the first N bytes. On de- compression, only one file will be decompressed, even if there are additional data at the end. XPK_InFH (BPTR) File handle to (de)compress from. It is not necessary that the handle is at the beginning of the file. Otherwise same rules as in XPK_InName apply. XPK_InBuf (STRPTR) Memory block to (de)compress. If you use this one, you have to specify InLen as well. XPK_InHook (struct Hook *) Hookfunc to deliver data for (de)compression. See special chapter on I/O hook functions. Must also supply XPK_InLen. IN ADDITION XPK_InLen (LONG) Specifies the number of bytes to read when compressing. ignored on decompression. THE OUTPUT TAGS. One of the five must be present. XPK_OutName (STRPTR) Name of file write (de)compressed data to. XPK_OutFH (BPTR) File handle to append (de)compressed data to. XPK_OutBuf (APTR) The memory block to write (de)compressed data to. Must also supply XPK_OutBufLen. On packing, its size must be at least inlen+inlen/32+2*XPK_MARGIN. On unpacking, it needs only be outlen+XPK_MARGIN. Use XpkExamine() to find out outlen. Note that this buffer must be word aligned. XPK_GetOutBuf (APTR *) Allocates a block of appropriate size and stores a pointer to it in the variable pointed to by ti_Data. Must also supply XPK_GetOutBufLen plus XPK_GetOutLen and can XPK_OutMemType. XPK_OutHook (struct Hook *) Hookfunc to accept (de)compressed data. See special chapter on I/O hook functions. IN ADDITION XPK_OutBufLen (LONG) The length of the output buffer you supply using XPK_OutBuf. For decompression, must be decompressed size (see XpkExamine()) plus XPK_MARGIN. For compression, inlen+inlen/32+2*XPK_MARGIN. XPK_GetOutLen (LONG *) Stores the total length of the (de)compressed data in the variable pointed to by ti_Data. Note: V2 of xpkmaster required for correct operation on compression. XPK_GetOutBufLen (LONG *) Stores the length of the buffer allocated for the data in the variable pointed to by ti_Data. FreeMem() the buffer you get from XPK_GetOutBuf with the length you get from XPK_GetOutBufLen. Note: For the number of bytes written, refer to XPK_GetOutLen! XPK_OutMemType (LONG) The type of memory to use for the output buffer. PACKING TAGS XPK_PackMethod (STRPTR) Use indicated method for packing. This would be a four letter string of uppercase characters and numbers. XPK_PackMode (LONG) Packing mode for sublib to use. Range is 0...100, where 100 is most efficient. XPK_StepDown (BOOL) Reduce packing efficiency to save mem if necessary. XPK_ChunkSize (LONG) Chunk size to try to pack with. May be altered by the master library. XPK_LossyOK (BOOL) Some packers, like MPEG, reduce the file size by deleting some information. These information cannot be restored. This tag tells xpkmaster.library if it is ok for you, that some information is deleted. It is FALSE by default. Use it with care! Should be used only with sound or picture files. QUERY TAGS XPK_PackersQuery (struct XpkPackerList *) Returns an array of available packers names in the XPLIST structure whose address is stored in the ti_Data field of this tag. XPK_PackerQuery (struct XpkPackerInfo *) Returns information about one single packer in the XPINFO structure whose address is stored in the ti_Data field of this tag. See xpk/xpk.h for the meaning of the fields therein. You must also supply XPK_PackMode. XPK_ModeQuery (struct XpkMode *) Returns information about one single packer mode in the XPINFO structure whose address is stored in the ti_Data field of this tag. See xpk/xpk.h for the meaning of the fields therein. You must also supply XPK_PackMethod and optionally XPK_PackMode (or a mode in the PackMethod string), otherwise the default mode will be used. OTHER TAGS XPK_GetError (STRPTR) Write error msg to the buffer passed. The buffer must be of size XPKERRMSGSIZE. This function calls XpkFault internally. XPK_Password (STRPTR) Use password for en- or decoding. Passing a NULL pointer or zero length string is equivalent to omitting this tag. XPK_ChunkHook (struct Hook *) Hook function to call between chunks. Can print a progress report, and if it returns a nonzero value, the (de)compression will be aborted. See special chapter on chunk functions. XPK_PassThru (BOOL) If true, data will just be handed trough on decompression if they were not packed. Otherwise you get XPKERR_NOTPACKED. XPK_TaskPri (UBYTE) The task priority to use during the (de)crunching. Use -1 for background decompression. XPK_FileName (STRPTR) The name to print in the progress report. If none is given, the InName will be used when packing and the OutName when unpacking. PREFERENCES RELATED TAGS XPK_UseXfdMaster (BOOL) (V4) If TRUE, xfdmaster.library will be used for checking unknown files. Useable with XpkUnpack() and XpkExamine(). Is FALSE by default, but depends on preference settings. XPK_UseExternals (BOOL) (V4) If TRUE, xex libraries in LIBS:compressors/extern will be used to check for crunched files. Useable with XpkUnpack() and XpkExamine(). Default value is TRUE (depends on prefs!) XPK_PassRequest (BOOL) (V4) If this is set a requester will be used to query the user for a password, if none is given. Useable with XpkPack(). This is disabled by default, but can be overridden using preferences settings. XPK_Preferences (BOOL) (V4) Tell xpkmaster.library whether to use its preferences system, or not. This is enabled by default. XPK_ChunkReport (BOOL) (V4) If this tag is set, xpkmaster.library brings an automatic chunk report request (when the preferences semaphore has a valid function for that). This is disabled by default. xpkmaster.library/--progress-- xpkmaster.library/--progress-- THE PROGRESS REPORT HOOK The progress report function is a standard hook function that will be called after every chunk (de)compressed. This will be about every 30K, or just twice if the file format is not split in chunks. If the field h_Entry in the hook is set, it will be called with the hook itself in A0 and the progress report structure in A1. If the progress report function returns a nonzero value, (de)compression aborts. NOTE: Because hooks are not called in program environment, they cannot be used in small data model of some compilers, as register A4 is not passed through. So the hook either has to be compiled in large data model or should use __saveds keyword of some compilers. xpkmaster.library/--data hooks-- xpkmaster.library/--data hooks-- GENERAL You have four methods of passing data to xpkmaster.library: file- names, filehandles, memory areas and hooks. The hooks are described here. The hook field h_Entry has to be standard hook functions and gets called with the hook itself in A0 and a pointer to a XpkIOMsg in A1. Commands are stored in xiom_Type field, data in the other fields. Return values are 0 or any of the XPKERR codes. Commands XIO_FREE and XIO_ABORT may be ignored. Whenever an error occurs, you have to return an XPKERR code and stop work. You get a XIO_ABORT call in this case later. When no error occured, return 0. You may store private data in the free fields of XpkIOMsg structure. You are always called with XIO_FREE or XIO_ABORT, so you can free private stuff there. Buffers can be freed, when next time a buffer allocation is required. NOTE: Because hooks are not called in program environment, they cannot be used in small data model of some compilers, as register A4 is not passed through. So the hook either has to be compiled in large data model or should use __saveds keyword of some compilers. BUFFERS Your hooks must be able to allocate buffers for read/write or pass pointers to them, when they are already allocated. There are some ways you have to handle this. First there is XIO_GETBUF. When getting this command you have to pass a memory pointer pointing to a region of at least xmm_Size size. For in hook there is another additionally method. When XIO_READ is wanted and xiom_Ptr is zero, then you have to pass (and allocate) a buf pointer and to fill it! The buffers must be valid until you are next time asked to allocate a buffer (either with XIO_GETBUF or XIO_READ). Then you may return old buffer pointer (when memory is large enough) or allocate a new buffer and free the old buffer. When XIO_ABORT or XIO_FREE is send all your buffers should be freed. NOTE: Your hooks do not get called only with your own buffers, but also with xpkmaster internally buffers! When your input data is already in memory, you may pass pointers to your memory regions and need not to allocate new memory for XIO_READ when pointer is zero. When xiom_Ptr is not zero for XIO_READ, you have to copy the data. Never expect, that you are called next time with buffer you allocated. There may be write cycles of headers and other stuff between XIO_GETBUF and XIO_WRITE. On reading it is equal. COMMANDS XIO_READ (in hooks only) This command is called all time xpkmaster.library needs some data. You have to fill the supplied memory area with input data of needed size (not more!) When the input memory pointer is zero, you have to allocate your own buffer and fill it. When you allocated a buffer before (either by XIO_GETBUF or XIO_READ) you can free it when pointer is zero. Input: xiom_Size size of required data xiom_Ptr already allocated buffer or zero Output: xiom_Ptr pointer to memory area of xiom_Size XIO_WRITE (out hooks only) This function is called, when some data was compressed and should be stored now. Copy the contents of buffer to your data storing system. Input: xiom_Size size of data xiom_Ptr pointer to memory area of xiom_Size Output: none XIO_FREE (both) You get this when work is finished, free all your stuff now. Input: none Output: none XIO_ABORT (both) You get this when work was aborted, because an error occured. Free all your stuff now. Input: none Output: none XIO_GETBUF (both) Asks you to pass a needed buffer. This buffer is not freed by xpkmaster.library. Do this when getting XIO_FREE, XIO_ABORT or the next XIO_GETBUF. Input buffers may be freed too, when XIO_READ is called with no pointer. Input: xiom_Size size of necessary buffer Output: xiom_Ptr pointer to the buffer XIO_SEEK (both) Change the current position in your data (like dos.library Seek command). When you are not able to handle seek, all better functions will fail. Pass XPKERR_NOFUNC in this case as return value. The offset you have to seek is always relative to current position. It can be negative too. Return value (xiom_Size) is same as for dos.library Seek command. Input: xiom_Size offset you have to seek Output: xiom_Size buffer position before seek XIO_TOTSIZE (both) You either have to tell the total input data size (in hook) or get told the total output data size (out hook). OUT HOOK: XIO_TOTSIZE may be ignored here. It tells you the maximum size of output file (the real size may be shorter). This is for example needed in memory hooks. This is only to inform you. This command never needs to return an error code. Input: xiom_Size total size of output data Output: none IN HOOK: XIO_TOTSIZE cannot be ignored here. When your hook cannot determine the total filesize, return any of the XPKERR values. XIO_TOTSIZE is called only, when xpkmaster library really needs filesize. Normal XPK files have size information in header and XPK_InLen flags supplies information for input. In these cases XIO_TOTSIZE is not used. But when returning an XPKERR, your hook will not work in other cases, when size is required. XIO_TOSIZE is used for following cases (when no XPK_InLen is supplied!): - decrunching of all non-xpk files - crunching of files NOTE: Only the size of the part, which should be processed, is wanted. Most time this is from current position to end of file (memory), but it may be shorter. But generally you have to calculate size starting at current position. Input: none Output: xiom_Size total size of input data